QuickDraw 3D Acceleration Layer (QAL) is a low-level abstraction layer for 3D hardware accelerators. Because QAL is an abstraction layer, it provides a common layer which can be used to access a variety of different hardware accelerators. QAL also provides a default software rasterizer which is always available, even on systems that don't have a hardware accelerator installed.
The QuickDraw 3D Interactive Renderer uses QAL to do all interactive rendering. As a result, QuickDraw 3D automatically works with any hardware accelerator which has a QAL plug-in.
QAL is shipping now (it's part of QuickDraw 3D).
WHY DISTRIBUTE A DDK?
Right now, QAL is being distributed in the form of a DDK (Device Driver Kit), primarily to hardware vendors who are developing 3D accelerators to run with QuickDraw 3D. This DDK is designed for that purpose.
QAL will soon be released as an SDK (Software Developer Kit) as well, for use by some specialized applications (such as 3D game development). If you're interested in using QAL as an API, you may find the enclosed DDK useful for some experiments. However, for serious work you will need to get the QAL SDK from Apple's Developer Support.
REASONS _NOT_ TO USE QAL AS AN API
— The #1 reason: QuickDraw 3D is much easier to use than QAL. QAL exposes many peculiarities of the windowing and hardware which are difficult to deal with cleanly, particularly for applications which must work with multiple monitors, all pixel formats, etc. And, of course, QuickDraw 3D has far more functionality than QAL, which is just a rasterization layer.
— Do NOT use QAL because it provides features that QuickDraw 3D does not support (e.g. different Z buffering modes, color pixmaps, Z buffer-less drawing). QuickDraw 3D 1.1 will provide all these features through the high-level API.
— Do NOT use QAL because it's "faster" — it isn't. The QuickDraw 3D Interactive Renderer uses QAL extremely efficiently; you won't gain any advantage by going "directly to the low-level calls".
— Do NOT use QAL because "I can write a renderer that's faster than QuickDraw 3D's Interactive Renderer". Apple has a substantial engineering effort working on our interactive renderer; you'll be a lot better off leveraging our efforts than trying to beat us.
— Do NOT use QAL because QuickDraw 3D doesn't have good datatypes for games. We are adding several new datatypes to QuickDraw 3D 1.1 which are excellent for game rendering, so you should at least learn about what's coming before starting to do your own.
WHEN SHOULD YOU USE QAL AS AN API?
— If you are a game developer who has already written an optimized 3D rendering engine, directly accessing QAL will likely be the easiest way for you to add support for 3D acceleration to your games.
— If you want to use a 3D accelerator for non-3D tasks (e.g. video compositing), QAL may be a more suitable API than QuickDraw 3D.
— And, of course, if you are a hardware developer you must use QAL to add plug-and-play support for your accelerator.
WHAT'S IN THIS DDK?
This DDK contains the 1.0.3 release of the QuickDraw 3D Acceleration Layer (QAL). This release matches the hardware acceleration interface of the QuickDraw 3D 1.0 release, so any QAL engine developed with this DDK will work with QD3D 1.0 (or later) based applications.
The contents of this DDK were all developed using the Metrowerks™ development environment, version 1.2GM. We recommend an on-line reference for Macintosh programming (e.g. the ThinkC™ Reference or QuickView™) as well, particularly if you're not an experienced Macintosh programmer.
TESTLINKED/TESTSHARED
TestLinked and TestShared are two versions of the QAL_Test application. The only difference between these versions is that TestLinked directly links in the empty drawing engine (described below), while TestShared loads the engine through the QAL plug-in mechanism. You can use whichever version of QAL_Test you like; usually it's easier to begin using the TestLinked version, and move to the TestShared version later. Note that you use the "SharedEmpty.µ" project to build your drawing engine as a shared library before you can use TestShared; see "USING SHARED LIBRARIES" below for more discussion.
QAL_Test opens two windows, using a different drawing engine for each window, and runs a series of simple QAL rendering tests to both windows. QAL_Test is primarily for vendors developing their own drawing engine, as it provides a convenient way to compare your results with those from the Apple Software drawing engine. However, this application also provides sample application code for how to use QAL for drawing.
QAL_Test runs tests that draw points, lines, Gouraud triangles and texture triangles. Each test is run four ways: Single buffered, double buffered, single buffered with 2D clipping, and double buffered with 2D clipping.
EMPTY ENGINE
QAL_Test includes "Empty Engine", a sample QAL drawing engine with empty stubs for the drawing functions. This provides a convenient place to begin implementing a drawing engine. The TestLinked.µ project file links "Empty Engine" directly with the QAL_Test application, so when you run it the second window is assigned to "Empty Engine". Nothing appears there, of course, as "Empty Engine" doesn't do anything. But that proves that it has actually been registered with the QAL manager! See "USING SHARED LIBRARIES", below, for how to build "Empty Engine" as a shared library instead of linking it directly.
QUICKDRAW™ 3D ACCELERATOR
"QuickDraw™ 3D Accelerator" is a shared library that contains the QAL manager and Apple's software rasterizer. You need to link with it whenever you are making QAL calls. Two versions are included, in two folders called "QD3D Accelerator (debug on)" and "QD3D Accelerator (debug off)". The debug on version does extensive parameter and semantic checking of all QAL calls; this is particularly useful when you are developing application code that drives QAL. The debug off version is the optimized release shipped with QuickDraw 3D 1.0, and performs no (or minimal) validation checking.
If you are developing a drawing engine, and you're confident that the application code is correct, you may find it more convenient to develop with the "QuickDraw™ 3D Accelerator" library that has debug turned off. This is because the debug on version actually inserts it's own functions and data types between the application calls (e.g. QADrawPoint()) and the drawing engine. If you use the debug off library, calls like this pass directly to your engine's code, which may be more convenient for debugging.
APPLE SOFTWARE RASTERIZER
This release includes "QuickDraw™ 3D Accelerator" version 1.0.3, which includes a software plug-in which implements a complete (although basic) QAL feature set. Some notes on the software rasterizer features:
— Rendering to any GDevice, and to 16 or 32 bit memory devices is supported. Rendering is optimized for 16 and 32 bit deep GDevices; all others are supported by rendering 16 bits offscreen and then blitting.
— Texture mapping is point-sampled from the closest mipmap level.
HEADERS
This folder holds the Drive3D.h and Drive3D_system.h header files, as described by the QAL ERS. Drive3D.h should be included by application code that uses QAL. Drive3D_system.h is only required by drawing engine code.
USING SHARED LIBRARIES
Your preferred "QuickDraw™ 3D Accelerator" library (i.e. with or without debugging) needs to be either in your application's folder (usually the most convenient for development) or in the System Extensions folder. The same is true of your drawing engine shared library (if present). In this DDK we've placed a copy of the debug-on "QuickDraw™ 3D Accelerator" library in the application folder, so right now the QAL_Test application is being run with debug on.
Once your drawing engine is stable, you may prefer to build it as a QAL shared library. The "SharedEmpty.µ" project demonstrates how to do this. In general it's pretty easy: Just build a shared library with creator 'tnsl', and call QARegisterEngine() from your init function. WARNING: Once you have built your engine this way, you should switch to using the TestShared application, as it will confuse the QAL manager to have your drawing engine both linked in and as a shared library!
As an experiment, try running the TestShared application _without_ the EmptyEngine plug-in in the application folder. The second window will be named "<No Drawing Engine>", indicating that the application wasn't able to find a second drawing engine to load. If you move EmptyEngine back into the application folder, the window will be titled "Empty Drawing Engine", indicating that the plug-in is being loaded.
Another experiment is to run TestLinked _with_ EmptyEngine in the folder. If you use the debug library, this will cause a warning message indicating that a duplicate drawing engine is being ignored. This is because the engine was registered twice, once from the linked version, and once via the plug-in mechanism. Therefore, if you're using TestLinked, you should not have a shared library version of the engine present as well.
